Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / asmtutr.arc / ASMGEN.DOC < prev next >

Wrap

Text File | 1984-03-30 | 25.5 KB | 595 lines

************************************************************************ * * * ASMGEN.COM - by J. Gersbach and J. Damke (Ver. 2.01) * * * * A program to generate cross-referenced assembly language code * * from any executable file. * * * * * * * * Uploaded to PCanada by Mark Magner November 23, 1983 * * * ************************************************************************ * PREFACE * This program will generate 8086/87/88 assembly code text that is compatible with the IBM Personal Computer Macro Assembler from any executable diskette file up to 65,535 bytes. The output can be routed to the console or a disk- ette file. A reference list may be generated separately or embedded at the appropiate instruction counter address in the assembly code. Some manual touch up will be required before reassembly, but nearly all the typing is done for you by ASMGEN and anything questionable is marked with "??". A file of sequential instructions may be resident on the same diskette to indicat to ASMGEN which addresses contain code, byted, words, or strings. This file may also include instructions to assume segment register values or toggle the output of assembley code text, generation of the reference table, 8087 mnemonics, of the inclusion of embedded reference information in the assembly file. DEBUG may be used to browse through the executable file to determine the starting locations of code and data to develop the sequential instruction file. It is important to accu- rately specify these locations for an accurate reference tabel and minimum touching up of the ASM output text. The number of references within the file determines the amount of memory required since a reference tabel is built in memory during the first pass. Disassembly is done from disk and only one file sector is in memory at any given time. Therefore memory size does not limit the size of the file to be disassembled. 48K bytes of memory will be enough for most programs but a few will need 64K or 128K. One diskette drive is sufficient but two is more convenient. * STARTING ASMGEN * There are two ways to work with ASMGEN: either by using the command menu or by calling ASMGEN with parameters. Following are the descriptions of both options. * USING THE ASMGEN MENU * The program is invoked by typing: ASMGEN You are then prompted for a file specification. Respond with the name of the executable file from which you wish to generate the assembly code. The executable file will normally have an extension of .EXE or .COM. ASMGEN will check this file spec for validity and then respond with a prompt that includes a summary of the command letters indicating that you may give it a command. The executable file contents are not checked for valid code and ASMGEN will try to dis- assemble text or compressed BASIC files and produce unintell- igible assembly code. The commands are: X filespec This file spec replaces any previous executable file spec. The usual file extension is .COM or .EXE EXAMPLE: X DATE.COM A <filespec> The executable file is disassembled and the assem- bly code is routed to the specified file. The usual file extension is .ASM. If the filespec is omitted, the output will default to the console. EXAMPLE: A DATE.ASM R <filespec> The reference table is sent to the file specified. The usual file extension is .TBL. If the filespec is omitted, the output will default to the console. EXAMPLE: R DATE.TBL Q The program is terminated and control returned to DOS. Each time a command has been executed, ASMGEN waits with a one line prompt for the next command. X <filespec>, A <CON>, R <CON> or Q ? The default filespec for each command is shown in brackets. Enter the next command of your choice as described above. * USING ASMGEN WITH PARAMETER CALLS * Up to three file specifications may be included when ASMGEN is first called from DOS. The executable file's name is given first, followed by specifications for the assembly and reference table files. EXAMPLE: ASMGEN DATE.COM, DATE.ASM, DATE.TBL If a semicolon follows the last filespec, ASMGEN will exit to DOS when the command has been executed. If no semicolon is entered, ASMGEN will display the menu options described above and wait for further input after executing the command. EXAMPLE: ASMGEN DATE.COM, DATE.ASM; If the filespec for the .ASM file and/or .TBL file is omitted, ASMGEN will generate first the .ASM file, then a .TBL file using the filename of the first filespec. EXAMPLE: ASMGEN DATE.COM,,; creates DATE.ASM and DATE.TBL and exits to DOS. If only the reference table is desired, the dummy name NUL should be entered in place of an .ASM filespec EXAMPLE: ASMGEN DATE.COM, NUL, DATE.TBL If only one filespec is given when the program is called, the reference table is built in memory and then the menu options are displayed for further commands. EXAMPLE: ASMGEN DATE.COM * PROGRAM EXECUTION * The disassembly is done in two passes through the scource file. On pass #1, the reference table is built in memory and the actual output is gen- erated during pass #2. Once the reference table is established, it remains in memory until an X or Q command is issued, and subsequent A and R com- mand executions skip pass #1. This saves a lot of time when the executable file is large. Three contiguous data areas are built dynamically in memory during pass #1. First is the compressed sequential instruction list. Second is a list of pointers for .EXE files that point to the locations of all relocatable variables in the program, also arranged in numerical order. These are established before reading any code. Third, the reference table is then built in a higher area of memory as pass #1 progresses. If all available memory in the program segment is filled before the first two data areas are completed, ASMGEN will abort to the command prompt. After the reference table is started, a shortage of memory will produce the message "Reference Table Incomplete Due to Insufficient Memory" and continue. Ctrl-Break may be used at any time to interrupt a command in progress. * READING THE ASSEMBLY CODE FILE (.ASM) * This file begins with a title taken from the executable file's name and date followed by the current date (in brackets). If not inhibited by the M switch in a SEQ file (explained later), the macro library will appear next in the file. Next will be a .RADIX 16 pseudo-op which tells the macro assembler that all numbers are in hexadecimal form. Then comes a header that indicates a starting value for the code segment, stack segment, instruction pointer and the stack pointer. The stack pointer is usually set to FFFF for .COM files but may be somewhat less depending on available memory. These values are passed by the linker for .EXE files. The first ASSUME statement might come next. There is one generated for each segment that begins with code. All segment registers are designated according to the current set of ASSUMEs. They will sometimes be incorrect, so all ASSUME statements should be checked prior to re-assembly. The disassembled output follows, terminated by an END statement and the execution address. An ORG psuedo-op is included if required. The text is compatible with the IBM Macro Assembler and the format is the same except for RETurns. To avoid the need for PROCedure titles, special mnemonics are provided for all RET instructions. These are defined in the macro library at the beginning of the file. Only macros that are needed for the current file are produced. The optional embedded commands that make up the reference table enhance the readability of the file. For very large files, this is sometimes undesirable and a separate reference table is best. When invalid instructions are encountered in code areas, they are reproduced as byte values followed by "??". If a near jump is defined previously in the code, and it is within range of a short jump, a NOP instruction is inserted after the jump. The executable file created with this .ASM file and the Macro Assembler and Linker will then be the same length as the original file. This makes it less important to differentiate between labels and numeric constants since the label values and their offsets within the file will be the same. The fundamental problem of disassembly is in knowing if the original assembly code defined a number as a label which changes as a function of it's position or as a number that always remains the same. If you make changes in the assembly code however, you must properly specify all values. You might as well remove all NOPs at the same time. Labels are five characters long and begin with "L". Segment labels begin with "S". The remaining characters are the current instruction counter in hex form, thus making each label unique and showing it's location in the original file. The instruction counter is continuous throughout the assembly code without resetting at segment boundaries. The segment labels are then in byte as opposed to paragraph form. In those cases where a label value is modified by an ASSUME statement, the original value is included as a comment in the referencing instruction so that it may be easily changed back if it was not intended as a location. The word "Relocatable" is printed at the end of any line that contains an ablolute paragraph value. These are values that DOS modifies after loading but befor executing a program. They are used for loading segment registers that are sensitive to the program location in menory. Relocatable values are not modified by ASSUMEs. ASMGEN converts these numbers from paragraph to byte values by multiplying them by sixteen so that they will fit within the 16-bit instruction counter field. When the paragraph value is negative or exceeds 0FFFH, it is left unchanged and a warning (??) is issued on that line. When a program larger than 64K bytes is being disassembled, it should be divided into smaller files. All words are produced as labels, except when the "L" switch has been enacted in the .SEQ file (explained later). The label name indicates it's numeric value and, if it does not occur on an instruction boundary, the name indicates it's position relative to the current instruction pointer is given by an EQU statement. Therefore the Macro Assember will assume that it is a location, but it is easily changed to a constant since the value is given in the label name. The word OFFSET precedes a label whenever it is questionable whether it is a label or an immediate value. You must decide which of the labels should be constants and which of the constants should be labels, and change them accordingly. When changing labels to numbers, be sure to append an "H" if the number ends with a "D" or a "B" since the Macro Assembler will otherwise assume that it is decimal or binary. Bytes are always treated as constants. An optional switch may be included in the .SEQ file (explained later) which enables numbers instead of labels if all references to the value are data segment and immediate operation types. An effective procedure to follow in attempting to understand the assembly code file is to look first for the message text area, the input commands, and the simpler subroutines. Then add label names to addresses in the .SEQ file (explained later) that remind the you of their purpose. Add comments to the labels. If these names are well chosen, the larger routines eventually will become clear. The embedded references are produced as labels so they will retain their meanings as they are changed. It is also helpful to spend some time studying the structure of data areas. Vector tables, which are frequently used to control the program's flow, reveal the program's structure very quickly. If some routines do not have labels at the beginning, it is usually because the code or tables that reference them (or the segment register assumptions) are not properly defined in the .SEQ file. * READING THE REFERENCE TABLE (.TBL) * A referencee is defined as a number that is referenced somewhere in the program. It may be a program loaction or a numeric constant. A referencor is is defined as the address in the program from which a refer- ence is made to the referencee. Each entry is composed of a referencEE followed by a list of referencors. If more than one line is needed, additional lines are indented to the first referencor position. The referencEE is followed by an "S" if it includes references to the beginning of segment. The referencor is followed by two letters, the first of which represents the segment register that is implied or prefixed in the referencing instruction. The second letter indicates the type of operation on the referencEE. When the reference entries are embedded in the assembly code, all values are preceded with the letter "L". ---------------------------------------------------------------------------- 1st letter | 2nd letter SEG REGISTER | TYPE OF OPERATION ---------------------------------------------------------------------------- C code | J jump M modify - INC, ADD, etc. S stack | C call I immediate - value or offset D data | R read T test or compare E extra | W write ? unknown or ESC instruction | P port ----------------|----------------------------------------------------------- * WRITING/READING THE SEQUENTIAL INSTRUCTION FILE (.SEQ) * The sequential instruction file is a list of special instructions to ASMGEN which the user creates. The file takes the form of a list of hexadecimal addresses and single-letter instructions or generation switches. If used, the .SEQ file must be on the same diskette as the source file and have the same name as the source file with an extension of .SEQ. Each instruction in the file must be in one of the following formats: addr command or addr command ;comment or addr command label comment or addr command label comment ;comment "addr" represents the instruction pointer value. All addr values must be in numerical sequence in the file. "command" may be either a toggle switch or a generation instruction. "label" is optional and replaces the label generated for this address with this non-blank string. "comment" is optional and must be preceded by "label" unless the dummy label "." is used. Everything following "label" is treated as an address comment and will be printed in the ASM file behind the generated instruction. The address comment may be up to 255 characters in length and should not contain a semi-colon. ";comment" is optional. Anything following a semi-colon in the .SEQ file instructions is considered as a comment in the .SEQ file only and is not added to the generated .ASM file. "label" and "comment" are not allowed when a generation switch is coded, but a ";comment" may be used to help clarify the .SEQ file. The .SEQ file is read into memory before the first pass starts. The addresses and commands will be compressed, but "label" and "comment" will be held in memory one to one. An effect of this is that memory space required for dis- assembly increases with each "label" and "comment" added to the .SEQ file. * DESCRIPTION OF GENERATION SWITCHES * THE VARIOUS TOGGLE SWITCHES ARE SET TO ON BY DEFAULT. Switches may be toggled on and off at any point in the .SEQ file/disassembly. All options switches except /M and /H can be either toggled or directly set by the user. A suffix of "+" turns the switch ON, and a suffix of "-" turns the switch OFF. Switches encountered in the file that have neither of these suffixes are toggled to the opposite of their state at the time; ON switches are turned OFF and OFF switches are turned ON. /B - generate byte references When ON, byte and word references are included in the reference table. When OFF, only word references are generated. /E - embedded references in ASM file When ON, reference table entries are inserted in the text just before the referencee's definition statement. When OFF, these entries are not included with the disassembled text. The entire reference table can be printed with the "R" command. /F - 8087 mnemonics When ON, ESC instructions are produced. When OFF, ESC instructions are assumed to be 8087 instructions and 8087 mnemonics are produced. /H - append hex "H" When this switch appears at any point in the .SEQ file, an "H" is appended to all hex numbers. This does not, of course, apply to the labels which are hex values preceded by the letter "L". The .RADIX 16 pseudo-op is omitted which allows the assembler's radix to default to decimal. This switch defaults to NO H APPEND. Note that it will be set only once. It retains it's value until the next .SEQ file is read. /L - generate label or number When ON, all word references are treated as labels. When OFF, a word reference is treated as a constant if all referencors are data immediate types. /M - suppress macro library When this switch appears at any point in the .SEQ file, no macro library is included in the text output. The DEFAULT IS THAT THE MACRO LIBRARY WILL BE INCLUDED. Note that this switch will be set only once. It retains it's value until the next .SEQ file is read. /O - control ASM output When ON, ASMGEN will output the generated text. When OFF, output will be suppressed. /R - control TBL output When ON, ASMGEN will output the generated reference data. When OFF, the reference table is not printed. /T - control trace output When ON, up to 16 bytes of object code are included as comments in each line of the assembly code file. When OFF, object code is not included. * DESCRIPTION OF .SEQ FILE COMMANDS * A - assume The following lines contain ASSUMptions for segment register values. They become effective at the address specified by this instruction and may be modified anywhere in the disassembly. The required format for assumptions is: & 0400 DS The ampersand indicates a continuation of the A instruction. In this example, a data segment beginning at a instruction pointer value of 400 will be assumed until another A instruction changes it. CS, ES, and SS are also supported. The segment assumptions are used for effective address calculations only. The code segment assumption does not affect the instruction pointer value. B - bytes The bytes encountered in the source file are assumed to have meaning as single byte values. C - code The bytes encountered in the source file are assumed to be valid 8088 machine language instructions. D - generate data operand The operand of the instructions is changed to immediate data. Subsequent bytes are interpreted as "C" (code follows). I - initial value for IP The hexadecimal value on this line overrides the instruction pointer value at the beginning of the file - not to be confused with the address at which execution begins. The default values are 0000 for EXE files and 0100H for COM and other files. The execution address following the END statement is omitted if this option is invoked. S - strings The bytes encountered in the source file are assumed to form text. Quoted text is produced for valid ASCII characters and byte values for others. # - defined length strings The first byte encountered in the source file contains the length of the character string which begins with the next encountered character. This length value may be overridden by a subsequent SEQ file instruction. $ - defined length strings The first byte encountered in the source file contains the length of the character string which begins with the next encountered character plus the length byte itself. This length value may be overridden by a subsequent SEQ file instruction. W - words Pairs of bytes encountered in the source file are assumed to have meaning as word values. X - repeating data structure A cyclic data structure is assumed to begin at the specified instruction pointer value. The structure definition may follow and is prefixed by an ampersand (&) to indicate the continuation of this instruction. If the definition does not follow, then the most recent definition is used. If no structure is yet defined, then an error message is displayed. The following elements may be used to define the structure: & NNNN S - The next NNNN bytes are defined as string characters & NNNN B - The next NNNN bytes are defined as byte values & NNNN W - The next NNNN bytes are defined as word values & XXNN $ - The next sequence of bytes is defined as NN fields. Each field consists of a length byte and a string of characters. The length of each field is contained in the first encountered byte. The high nibble (XX), if non-zero, is a bit mask of the length field within the byte. The length field is right-justified within the byte after the byte value is sent to the output file. * EXAMPLES OF .SEQ COMMANDS * This example .SEQ file shows all the possible instructions in the appropriate format. ;All switches are on at the beginning. 0 /T ;no object code as comments in output 0 /M ;no macro library in output 0 /H ;append "H" to all numbers 00H /A ;assume the following segment values ;Note that the ampersand (&) indicates the extended ASSUME & 380 DS ;the data segment starts at 380 hex & 380 ES ;the extra segment starts at 380 hex 0200 I ;initialize the instruction pointer to 200 0200 /F ;introduce 8087 mnemonics (not ESC) 0200 /E ;no embedded references 0200 C ;code begins at 200 0203H W ;words are at 203 0207 C ;more code starting here 220 X ;complex data structure begins here & 3 W ;words & 1 B ;byte & 0E02 $ ;2 strings starting with the 2nd byte follow ;bits 3,2,1 of the first byte contain the length of the ;string including the length byte. ;the high nibble (0E) is the mask. ;see also # in summary below & 1 B ;byte ;the structure repeats until 351 351 B ;bytes 358 C ;more code 380 S ;strings - list of messages 421 W ;words 4FD /B ;no further byte references 502 /R ;garbage here - turn off reference generation 502 /O ;and output 600H /O+ ;valid code - turn output back on 600 /R 600 C 1A60 /O- ;output file about to fill diskette - turn output off but keep ;scanning for references. ;another run will be needed to get the remaining code. 1B00 /D ;treat operand as immediate data 1DFD /B+ ;continue with byte references 1F45 W user_prt ;user provided labels will translate 2256 S $MSG ;to upper case Comments may be included if preceded by a semicolon. Alphabetic characters may be either upper or lower case. An "H" may follow the hex address. * SAMPLE SESSION * The external command CHKDSK.COM will serve as an example for this sample session because it is short. The .SEQ file is also short and easy to generate. Only these few instructions are needed. 0100 /T ;include object code as comments in .ASM file 0100 /E ;simpler output without references 04F7H S ;messages 04F7H /H ;append "H" to numeric values Using DEBUG, browse through CHKDSK.COM to see how this was arrived at. Usually, but not always, the best procedure is to assume code. If the code appears unintelligible, display it in hex/ASCII. If it is not text, assume bytes. Label positions in the first disassembly may indicate that some locations should be words. Next, generate the .ASM file by typing ASMGEN CHKDSK.COM <enter> A <enter> The assembly code can be viewed on the screen. Then type A CHKDSK.ASM <enter> to save the assembly source code to a file. Then, R CHKDSK.TBL <enter> to save the cross-reference table to disk. The Macro Assembler, Link.exe and Exe2bin could now be used to assemble CHKDSK.ASM, link it to .EXE and convert it to a .COM file. No modification should be necessary in this case. If working with code that is to be modified, the symbol types must be correctly specified as locations or as constants. If they are constants, place them outside of any segment. The label names may then be changed to make the code more readable. ENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDENDEND END OF TRANSFER - PRESS ENTER TO RETURN TO MENU